\documentstyle{report}
\title{SPARCBench User's Manual}
\author{\copyright Electronetics, Inc. 1992}
\date{1 February 1992}
\begin{document}
\maketitle
\section*{Introduction}

The SPARCBench package consists of a SPARC$^{TM}$ cross-assembler
(sasm), user-code simulator (ssim), and a disassembler (dis), all of
which run under MSDOS.  These tools are based upon Version 7 of the
SPARC Architecture Manual.

Ssim attempts to simulate the user-code instruction set of the SPARC
cpu as run under SunOS.  It makes no effort to simulate privleged
(kernel mode) instructions.  It also functions completely within the
limits of MSDOS.  This means that many system calls (particularly
those dealing with multiprocessing and networking) either return
ENOSYS (not implemented) or EINVAL (invalid).

Ssim is {\bf not} intended as a vehicle to simulate large SPARC binaries.
First, the performance would be miserable.  On a 10Mhz 8086 laptop,
between 1000 and 2000 SPARC instructions per second are simulated.
Secondly, the missing system call functionality mentioned previously
precludes running just about any large (and many small) SPARC binaries.

So, what good is ssim?  It is mainly intended for those wishing to
learn the SPARC instruction set as an assembly language.  The SPARC
instruction set is small, regular and has other RISC-like properties.
SPARC hardware provides the best method for learning the instruction
set.  Ssim allows MSDOS hardware to function as a substitute.  It also
has a rudimentary tracing capability to record addresses of code
execution and data read/write.

A cross assembler (sasm) is included so you can write your own SPARC
assembler programs and execute them using ssim.  There is no linker.
Since ssim is targeted for small hand-written programs, sasm assembles
entire complete programs directly into NMAGIC (to save disk space)
SPARC executables.  Ssim can handle ZMAGIC format binaries also, as
long as they are less than 64k total text and data size :-).  The
output of sasm will indeed run on actual SPARC hardware.

Ssim contains a simple interactive debug environment for stepping
through SPARC code execution.  Its user interface is modelled after a
subset of the GNU debugger gdb.

\section*{Installation}

The files included in this version of the SPARCbench tools are listed
in the file FILELIST.DOC.  You should verify that you have the files
mentioned in this list.

A set of confidence tests is provided to verify proper operation of
sasm and ssim.  These are run as regression tests when modifying or
adding new code.  You may wish to run them when setting up the
SPARCbench package.  To do so, execute the .BAT file \verb+CTEST.BAT+.
The output should match the contents of the file \verb+EXPECT.OUT+.

\section*{SASM Cross-assembler}

Sasm creates NMAGIC SPARC executables from assembler source code.  It
will assemble most privileged instructions as well as non-privileged.
Privileged code is not supported in ssim and will cause the program
being simulated to receive an illegal instruction signal.  Comments
are enclosed within /* */ delimiters (C-style) or extend from a 
{\frenchspacing !} to
end of line.  Since SASM has no concept of a program extending over
multiple source files, all references must be resolved within the file
being assembled.  The following pseudo-ops are supported in the same
fashion as the SUN4 SPARC assembler:

\begin{verbatim}
.align -- align location counter; argument is 2, 4, or 8
.ascii -- Generate 1 or more comma-separated strings
.asciz -- Same as .ascii but strings are null terminated
.byte  -- Generate initialized bytes, comma separated
.half  -- Generate initialized halfwords, comma separated
.seg   -- Set current segment to "text", "data", or "bss"
.skip  -- Allocate empty space in current segment
.word  -- Generate initialized words, comma separated
\end{verbatim}

Identifiers must begin with an upper or lower case letter, underscore
('\verb+_+'), dollar sign ('\verb+$+') or period ('\verb+.+').
Additional characters may be digits as well.  Numeric labels are not
supported by sasm.

The following register names are recognized by sasm.
The numeric notation \verb+%n+ (e.g., \verb+%22+) is not supported.
The \verb+%hi+ and \verb+%lo+ operators are not supported either.

\begin{verbatim}
%g0  %o0  %l0  %i0  %f0  %f8   %f16  %f24  %c0  %c8   %c16  %c24
%g1  %o1  %l1  %i1  %f1  %f9   %f17  %f25  %c1  %c9   %c17  %c25
%g2  %o2  %l2  %i2  %f2  %f10  %f18  %f26  %c2  %c10  %c18  %c26
%g3  %o3  %l3  %i3  %f3  %f11  %f19  %f27  %c3  %c11  %c19  %c27
%g4  %o4  %l4  %i4  %f4  %f12  %f20  %f28  %c4  %c12  %c20  %c28
%g5  %o5  %l5  %i5  %f5  %f13  %f21  %f29  %c5  %c13  %c21  %c29
%g6  %o6  %l6  %i6  %f6  %f14  %f22  %f30  %c6  %c14  %c22  %c30
%g7  %o7  %l7  %i7  %f7  %f15  %f23  %f31  %c7  %c15  %c23  %c31

%fp  %sp  %fq  %cq  %y   %fsr  %csr  
\end{verbatim}

The following instructions are not supported by sasm.  Except for
these, all opcodes (and their synonyms) as defined in the Version 7
SPARC Architecture Manual are supported. Additionally, ``b" is allowed
as a synonym for ``ba".

\begin{verbatim}
coprocessor branch instructions
coprocessor operate instructions
return from trap instruction ("rett")
Instructions using the %psr, %wim and %tbr registers.
\end{verbatim}

Only the following pseudo-instructions are allowed.

\begin{verbatim}
nop    cmp   tst    ret
retl   set   inc    inccc
dec    deccc clr    clrb
clrh   mov
\end{verbatim}

Sasm requires the name of the assembler source file on its
command line.  Other accepted options are:

\begin{itemize}
\item[\verb+-g+] Cause line number
and symbol value information to be added to the executable.
It can then be debugged with a debugger such as gdb or
the interactive mode of ssim.

\item[\verb+-n+] Do not display version and copyright banner.

\item[\verb+-o+] Specify the name of the output file.
The default is \verb+a.out+.

\item[\verb+-l+] Cause lines from the input file to
be echoed during the first pass of assembly.
\end{itemize}

Sasm silently allows the use of \verb+set+ in a delay slot.
It does not understand any kind of macros, nor does
it understand the \verb+ld2+ pseudo-instruction sometimes
output by the Sun C compiler.


\section*{SSIM Simulator}

Ssim has several limitations that are forced by the nature of the 1
Megabyte real-address space available under MSDOS.  No swapping or
paging of any kind is attempted by ssim.  The amount of virtual
address space available to the SPARC program is determined by the
amount of free physical memory on the MSDOS host.  This version of
ssim has the additional limitation that it will not simulate programs
requiring more than 64k total text and data space. This limitation may
be relaxed in a future version.

All SPARC addresses are related to MSDOS addresses by a single offset
which is either added or subtracted.  This means that the top of stack
is not nearly as high in the address space as on real SPARC hardware
with virtual memory.  Because of this, (SPARC) stack overflow becomes
a real possibility.  Ssim does not make any kind of check for stack
overflow.  When ssim examines a SPARC address for validity, it only
checks to see if the corresponding MSDOS address is outside the block
allocated for SPARC memory.  If so, a segmentation fault is incurred
and the program terminates (unless it handles SIGSEGV).  Since the
beginning of SPARC memory is at address 0x2000, NULL pointer
dereferencing will generate a SIGSEGV.  Any address from 0x2000 to the
top of stack can be read, written and executed.  There is no unmapped
gap between the top of the heap and bottom of the stack as on real
hardware.  Alignment restrictions for load and store instructions are
enforced by ssim.  A SIGBUS results from an unaligned access.

\subsection*{Options}
If no filename is given when invoking ssim, the default name
\verb+a.out+ is assumed.  Several options modify the simulator's
behavior. Any of these options (except \verb+-d+) will cause
SPARC code to execute slower due to additional checking.

\begin{itemize} \item[\verb+-c+] Write an execution trace to the file
``code.tra".  The code trace consists of a sequence of 32-bit words
giving the SPARC virtual address of each instruction executed.

\item[\verb+-d+] Write a load/store trace to the file ``data.tra".  The
data trace consists of a series of five-byte records.  The first byte
identifies the type of access (e.g. load unsigned byte).  The
following four bytes are the SPARC address involved.  The file
\verb+dtrace.c+ contains an example program for analyzing this type of
trace.

\item[\verb+-g+] Interactive mode.  The debug interface is invoked
prior to execution.  Startup commands are read from the file
``ssim.ini" if it exists.  The help command summarizes the others.

\item[\verb+-i+] Keep a count of instructions (mod $2^{32}$) executed.

\item[\verb+-n+] Do not display version and copyright banner.

\item[\verb+-v+] Verbose.  Disassemble each instruction prior to
execution.
\end{itemize}

\subsection*{Debugger Interface}
The interactive debugger interface within ssim is modeled
after a subset of the GNU debugger gdb.  Any command using
line number or symbol value information will require that
the source be assembled with sasm's \verb+-g+ flag.
Debugging executables produced by other means may produce
confusing results. (e.g., the ssim debugger expects only
one source file).  The debugger is activated by specifying
the \verb+-g+ option to ssim.  If the startup file ``ssim.ini"
exists in the current directory, it will be opened and read
for startup commands prior to user interaction.

The following commands are available within the debugger:

\begin{tabular}{lp{2.85in}}
\verb+run [args]+ & Execute the program with the specified arguments. \\
\verb+quit+ & Exit ssim. \\
\verb+help+ & Summarize the available commands. \\
\verb+break arg+ & Set a breakpoint at the given argument.  If the
argument is an integer, it is assumed to be a line number.  Breakpoints
can also be set at virtual addresses (e.g., ``break *0x2cd0"). Up to
10 breakpoints may be set. \\
\verb+info+ & Summarize current breakpoints. \\
\verb+cont+ & Continue SPARC program execution. \\
\verb+display arg+ & Display the symbol or register argument whenever control
returns to the debugger.  Up to 10 display elements may be set.  There
is no way to remove display elements in the current version. \\
\verb+print arg+ & Print the value of a symbol or register argument. \\
\verb+verbose+ & Toggle the verbose flag. \\
\verb+handle n arg+ & Control signal handling for signal n. Options
are [no]stop or [no]print. \\
\verb+disassemble [args]+ & Disassemble code starting at the PC or specified
argument(s). \\
\verb+delete [arg]+ & Delete some or all breakpoints. \\
\verb+address arg+ & Print the address of a symbol. \\
\verb+trace arg+ & Turn on code/data tracing as with -c/-d on command line. \\
\verb+untrace [arg]+ & Turn off code/data tracing. \\
\verb+list [args]+ & List source code starting at the PC or specified line
number(s). \\
\verb+next+ &  Step to the next line of code.\\
\end{tabular}

Only enough characters to uniquely specify a debugger
command are necessary.  Most of the commands are patterned
after the GDB command interface.
Debugger arguments must be separated by spaces.
Any debugger input line with \verb+'#'+ in column 0 is ignored.
The register names recognized by the debugger include:

\begin{verbatim}
  $g0,  $g1,  $g2,  $g3,  $g4,  $g5,  $g6,  $g7, 
  $o0,  $o1,  $o2,  $o3,  $o4,  $o5,  $sp,  $o7, 
  $l0,  $l1,  $l2,  $l3,  $l4,  $l5,  $l6,  $l7, 
  $i0,  $i1,  $i2,  $i3,  $i4,  $i5,  $fp,  $i7, 
  $f0,  $f1,  $f2,  $f3,  $f4,  $f5,  $f6,  $f7, 
  $f8,  $f9,  $f10, $f11, $f12, $f13, $f14, $f15, 
  $f16, $f17, $f18, $f19, $f20, $f21, $f22, $f23, 
  $f24, $f25, $f26, $f27, $f28, $f29, $f30, $f31, 
  $pc,  $npc, $y,   $fsr, $car, $zer, $ovf, $neg
\end{verbatim}


\subsection*{System Calls}
The following system calls are supported in the MSDOS
version of ssim.  All supported system calls are subject
to any applicable MSDOS limitation.

\begin{verbatim}
1: exit     10: unlink    33: access    64: getpagesize
3: read     12: chdir     37: kill      108: sigvec
4: write    17: sbrk      38: stat      136: mkdir
5: open     19: lseek     47: getgid    137: rmdir
6: close    20: getpid    54: ioctl     139: setcontext
8: creat    24: getuid    62: fstat
\end{verbatim}

The getpid() call always returns 0x2000.  Similarly, getuid()
always returns 100.  The kill() call returns EINVAL if the signal
is sent to any process other than 0x2000.  The getgid() call
always returns 10.  Ioctl() calls will almost certainly not
have the desired effect.  The setcontext() call is used to
return from the sigtramp signal handler dispatcher.

\subsection*{Limitations}
In the interest of simplicity, ssim does not implement any extended
precision floating point instructions.  Also the SPARC environment
is empty in the current version.  A future version of ssim may make
the DOS environment accessible to SPARC code.  In addition,
since the \verb+mmap()+
system call is not yet implemented, ssim cannot execute dynamically
linked executables.

\section*{Example Code}
The confidence tests contain several examples of SPARC
assembly code that may be useful references.  There are examples
which show the use of signal handling, accessing the command
line and other things.  All of these tests were assembled with
sasm and ran the same (except for speed, of course) on a
SparcStation 2 platform as they do under ssim.  Some of them
use the exit status to communicate information.

\section*{Disassembler}
Dis is the SPARCBench assembler.  It attempts to disassemble
the text segment of SPARC executables.  If the \verb+-r+ (raw) option is
given, disassembly starts at the first word in the file.  Otherwise,
the 32 byte executable header is skipped.  The \verb+-n+ option also
is available and prevents the version/copyright banner from being printed.

\section*{Support and Licensing}
If unexpected operation is encountered, the following procedure
ought to be used to communicate a bug report to Electronetics, Inc.

First, try to isolate the problem as much as possible with the
ssim debugger.  Write a short self-contained SPARC assembler file
which should be acceptable to sasm.  Send it with an explanation
of the unexpected behavior to the address below.  

\begin{center}
\begin{verbatim}
Electronetics, Inc.
3101 111th Street S.W.
Everett, WA  98204
\end{verbatim}
\end{center}

The SPARCBench tools are implemented in C and are available on Sun
and Apollo workstations as well as MSDOS hardware.  They are Copyright
Electronetics, Inc. 1992. The binary MSDOS version of the tools may
be freely redistributed in its original ZOO archive format.  Other
distribution is not allowed.  A copy of the current MSDOS binary
may be obtained by sending US$15 to Electronetics at the above address.
Complete C source code is available for US$150.
Additional tools may be added to the package in future
versions.  Please contact Electronetics, Inc.  at the above address
for further details.

SPARC is a trademark of Sun Microsystems, Inc.
\end{document}
